KrakenD

Since KrakenD 2.5, the integration with Moesif and KrakenD is natively supported. This means the only thing needed is some config within the krakend.json file.

Enabling the Moesif plugin in KrakenD

Since the Moesif plugin is available in KrakenD by default, the only thing required to enable Moesif in KrakenD is to add a telemetry/moesif entry into the krakend.json configuration file. To push data to your Moesif account, you must add your Moesif Application ID to this config.

In order to track Users and Companies in Moesif, you must add few additional settings that are covered further down on the page.

Below is an example of a krakend.json file that includes the extra_config section to use Moesif with KrakenD. The application_id field is the only value that is required.

{
  "version": 3,
  "extra_config": {
    "telemetry/moesif": {
      "@comment": "Push user activity to Moesif based on the information contained in JWT, every second, in batches of 1000 events",
      "application_id": "Sign in to get your Moesif Application Id",
      "debug": false,
      "log_body": false,
      "event_queue_size": 1000000,
      "batch_size": 1000,
      "timer_wake_up_seconds": 1
    }
  }
}

See additional documentation from KrakenD for more details.

Tracking Users

To allow Moesif to track API calls by a user ID, you can identify the user that made the call through the JWT they use. To do this, you’ll need to set the user_id_headers parameter within the configuration. Additionally, if using a JWT you’ll need to also set the user_id_jwt_claim parameter.

Setting the user_id_headers

In the Moesif configuration, you will need to add the user_id_headers field. This field defines the list of possible headers that can identify a user uniquely. When the header is Authorization and the auth type is Basic, KrakenD will automatically extract the username with no additional configuration.

If tokens are used and passed as an Authorization: Bearer header, KrakenD will extract the user ID from the JWT claim based on what is configured in the corresponding user_id_jwt_claim field (covered below).

In the case where multiple headers may contain the user information, an array of options can be passed. Below is an example of an array with multiple headers.

"user_id_headers": [
  "X-User-Id",
  "Authorization"
],

Of the list that is passed, all entries are tested in the given order. The first header to match in the list is used to extract the user ID (successfully or not).

Setting the user_id_jwt_claim

When using JWT tokens, the user_id_jwt_claim defines which claim in the JWT contains the user ID. The field must be a string. By default, KrakenD will use the value that is stored in the JWT’s sub claim. Below is an example of how to set up KrakenD to use a JWT to extract a user ID.

"user_id_jwt_claim": "sub",
"identify_company": {
  "jwt_claim": "company_id"
},

Tracking Companies

Identifying the company to which an API call (and user) belongs can be done in 3 different ways: through a JWT claim, header value, or query string. It’s important to note that only one of these methods can be used at a time.

Via JWT Claim

To identify a company through a value in the JWT claim, you’ll want to specify which field in the JWT claim should be used. If your JWT payload looks similar to this:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "company_id": "123myCompany"
}

you can add the following to your krakend.json Moesif configuration:

"identify_company": {
  "jwt_claim": "company_id"
},

Note: the value where company_id is can be the name of whatever field you’d like to extract from the JWT.

Via Request Header

To extract the company ID from a header, you will need to use the header option and specify which header to retrieve the value from. For instance, if there is a header in the request called X-Company-Id, it could be extracted by using the following entry in your config.

"identify_company": {
  "header": "X-Company-Id"
},

Via Query String

To extract the value from a query parameter, you can use the query_string option and specify which query string the value should be extracted from. For instance, if a request contains a ?company_id=123mycompany query string, the company ID could be extracted using the following entry in your config:

"identify_company": {
  "query_string": "company_id"
},

Parameters

Below is a list of all the parameters that can be added to the krakend.json configuration file within the Moesif configuration object (telemetry/moesif).

Key Title Description Type Default Examples
application_id Collector Application ID The Collector Application ID is used to send events, actions, users, and companies to Moesif’s Collector API. Moesif provides it under the ‘API Keys’ section. string    
debug Enable debug Set to true when configuring Moesif for the first time while in development, to see the activity in the logs. Set to false in production. boolean false  
log_body Send the body Send the body of all endpoints and requests to Moesif. boolean true  
event_queue_size Event Queue Size Sends the number of events you can hold in-memory to send them asynchronously to Moesif. If the throughput of your API generates more events than the size of the queue, the exceeding events will be discarded and not reported. integer 1000000  
batch_size Batch Size Number of events you will send on every batch reporting asynchronously to Moesif. For high throughput you will need to increase this value. integer 200  
timer_wake_up_seconds Timer Wake Up Specifies how often a background thread runs to send events to Moesif. Value in seconds. integer 2  
request_header_masks Request header masks The list of request headers that you want to mask their values before sending them to Moesif. array   [“Authorization”]
response_header_masks Response header masks The list of response headers that you want to mask their values before sending them to Moesif. array   [“Cookie”]
request_body_masks Request body masks The list of fields in the request body that you want to mask before sending them to Moesif. You can set log_body to false to prevent any body being sent. array   [“password”, “credit_card”]
response_body_masks Response body masks The list of fields in the response body that you want to mask before sending them to Moesif. You can set log_body to false to prevent any body being sent. array   [“password”, “credit_card”]
user_id_headers User ID headers Defines the list of possible headers that can identify a user uniquely. array   [“X-User-ID”, “Authorization”]
user_id_jwt_claim User ID JWT claim When using JWT tokens, it defines which claim contains the user ID. The field must be a string. string “sub”  
identify_company Identify company It sets which strategy you want to use to identify the company. Identifying the company helps you efficiently govern your API. Choose the system you wish to apply (declare only one property). object   jwt_claim, header, query_string

Example Config

Here is an example of a krakend.json that includes the elements required to track users and companies.

{
  "version": 3,
  "extra_config": {
    "telemetry/moesif": {
      "@comment": "Push user activity to Moesif based on the information contained in JWT, every second, in batches of 1000 events",
      "application_id": "yourapplicationid",
      "user_id_headers": [
        "Authorization"
      ],
      "user_id_jwt_claim": "sub",
      "identify_company": {
        "jwt_claim": "company_id"
      },
      "debug": false,
      "log_body": false,
      "event_queue_size": 1000000,
      "batch_size": 1000,
      "timer_wake_up_seconds": 1
    }
  }
}

Updated: